<HTML>
<HEAD>
<TITLE>TSP (audio) - PQevalAudio</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFACD">
<H2>PQevalAudio</H2>
<HR>
<H4>Routine</H4>
<DL>
<DT>
PQevalAudio [options] AFileR AFileT
</DL>
<H4>Purpose</H4>
<DL>
<DT>
Evaluate the perceptual quality degradation for audio files
</DL>
<H4>Description</H4>
This program takes a reference audio file and a test audio file and measures
the perceptual degradation of the test signal with respect to the reference
signal. The measurement is based on the ITU-R BS.1387 (PEAQ) standard. The
output combines a number of model output variables (MOV's) into a single
measure, the Objective Difference Grade which is an impairment scale with the
following meanings.
<PRE>
   0 imperceptible
  -1 perceptible but not annoying
  -2 slightly annoying
  -3 annoying
  -4 very annoying
</PRE>
<P>
The measurement procedure has only been calibrated for a sampling rate of
48 kHz. The measurement procedure works for monaural or binaural (stereo)
signals. Use ResampAudio to resample audio files with other sampling rates
to 48 kHz. The measurement procedure also assumes that the files have been
time and gain aligned. Use CompAudio to determine the required gain and
delay compensation and CopyAudio to actually modify the gain and time-align
the files.
<P>
This program implements the basic version of PEAQ. The measurement results
on a standard database do not fall within the tight bounds specified in the
standard (see the report cited below for a discussion of the difficulties
in interpreting the standard). However, the results are close enough to be
useful for quality impairment measurements.
<P>
<DL>
<DT>
References:
</DL>
ITU-R Recommendation BS.1387, "Method for Objective Measurements of Perceived
Audio Quality", Dec. 1998 (and subsequent corrections).
<P>
T. Thiede et al, "PEAQ - The ITU Standard for Objective Measurement of
Perceived Audio Quality", J. Audio Eng. Soc., vol. 48, pp. 3-29, Jan.-Feb.
2000.
<P>
P. Kabal, "An Examination and Interpretation of ITU-R BS.1387: Perceptual
Evaluation of Audio Quality", TSP Lab Technical Report, Dept. Electrical &amp;
Computer Engineering, McGill University, May 2002.
(http://www.TSP.ECE.McGill.CA/MMSP/Documents)
<H4>Options</H4>
<DL>
<DT>
Input file(s): AFileR AFileT:
<DD>
The environment variable AUDIOPATH specifies a list of directories to be
searched for the input audio file(s).  Specifying "-" as the input file
indicates that input is from standard input.
<DT>
-g GAIN, --gain=GAIN
<DD>
A gain factor applied to the data from the input files.  This gain
applies to all channels in a file.  The gain value can be given as a
real number (e.g., "0.003") or as a ratio (e.g., "1/256"). This option
may be given more than once.  Each invocation applies to the input files
that follow the option.
<DT>
-l L:U, --limits=L:U
<DD>
Sample limits for the input files (numbered from zero).  Each invocation
applies to the input files that follow the option.  The specification
":" means the entire file; "L:" means from sample L to the end; ":U"
means from sample 0 to sample U; "N" means from sample 0 to sample N-1.
<DT>
-L LEVEL --levelSPL=LEVEL
<DD>
Listening level (in dB SPL) for a maximum amplitude sine (default 92 dB
SPL)
<DT>
-i NI --info==NI
<DD>
Print information for each NI'th PEAQ frame. The default is chosen to
print PEAQ frame information for at most 50 frames. Set NI to zero to
suppress the printout of intermediate information.
<DT>
-o OPTIONS --options=OPTIONS
<DD>
Processing options.
<PRE>
  "clip_MOV" or "no_clip_MOV" - Clip MOV values (default "no_clip_MOV")
  "PC_init=V" - Initial value for the pattern correction factors
    (default 0)
  "PD_factor=V" - Forgetting factor for the maximum probability of
     detection calculation (default 1).
  "overlap_delay" or "no_overlap_delay" - Overlap warmup frames (frames
    before the data boundary) and the delay for calculating modulation
    difference and noise loudness values (default "overlap_delay")
  "data_bounds" or "no_data_bounds" - Ignore frames with small data
    values at the beginning and end of the reference (default
    "data_bounds")
  "end_min=N" - Stop processing at the frame that contains at least
    N samples (default value of N is 1024). The "-l" command line option
    can be used to shift the entire processing. For instance "-l -1024:"
    will add half a frame of zero padding before the start of data.
</PRE>
<DT>
-t FTYPE, --type=FTYPE
<DD>
Input audio file type.  In the default automatic mode, the input file
type is determined from the file header.  For input from a non-random
access file (e.g. a pipe), the input file type can be explicitly
specified to avoid the lookahead used to read the file header.  This
option can be specified more than once.  Each invocation applies to the
input files that follow the option.  See the description of the
environment variable AF_FILETYPE below for a list of file types.
<DT>
-P PARMS, --parameters=PARMS
<DD>
Parameters to be used for headerless input files.  This option may be
given more than once.  Each invocation applies to the input files that
follow the option.  See the description of the environment variable
AF_NOHEADER below for the format of the parameter specification.
<DT>
-h, --help
<DD>
Print a list of options and exit.
<DT>
-v, --version
<DD>
Print the version number and exit.
</DL>
<H4>Environment variables</H4>
<DL>
<DT>
AF_FILETYPE:
</DL>
This environment variable defines the input audio file type.  In the default
mode, the input file type is determined from the file header.
<PRE>
  "auto"       - determine the input file type from the file header
  "AU" or "au" - AU audio file
  "WAVE" or "wave" - WAVE file
  "AIFF" or "aiff" - AIFF or AIFF-C sound file
  "noheader"   - headerless (non-standard or no header) audio file
  "SPHERE"     - NIST SPHERE audio file
  "ESPS"       - ESPS sampled data feature file
  "IRCAM"      - IRCAM soundfile
  "SPPACK"     - SPPACK file
  "INRS"       - INRS-Telecom audio file
  "SPW"        - Comdisco SPW Signal file
  "CSL" or "NSP" - CSL NSP file
  "text"       - Text audio file
</PRE>
<P>
<DL>
<DT>
AF_NOHEADER:
</DL>
This environment variable defines the data format for headerless or
non-standard input audio files.  The string consists of a list of parameters
separated by commas.  The form of the list is
<PRE>
  "Format, Start, Sfreq, Swapb, Nchan, ScaleF"
</PRE>
<DL>
<DT>
Format: File data format
<DD>
<PRE>
 "undefined" - Headerless files will be rejected
 "mu-law8"   - 8-bit mu-law data
 "A-law8"    - 8-bit A-law data
 "unsigned8" - offset-binary 8-bit integer data
 "integer8"  - two's-complement 8-bit integer data
 "integer16" - two's-complement 16-bit integer data
 "integer24" - two's-complement 24-bit integer data
 "integer32" - two's-complement 32-bit integer data
 "float32"   - 32-bit floating-point data
 "float64"   - 64-bit floating-point data
 "text"      - text data
</PRE>
<DT>
Start: byte offset to the start of data (integer value)
<DT>
Sfreq: sampling frequency in Hz (floating point number)
<DT>
Swapb: Data byte swap parameter
<DD>
<PRE>
 "native"        - no byte swapping
 "little-endian" - file data is in little-endian byte order
 "big-endian"    - file data is in big-endian byte order
 "swap"          - swap the data bytes as the data is read
</PRE>
<DT>
Nchan: number of channels
<DD>
The data consists of interleaved samples from Nchan channels
<DT>
ScaleF: Scale factor
<DD>
<PRE>
 "default" - Scale factor chosen appropriate to the type of data. The
    scaling factors shown below are applied to the data in the file.
    8-bit mu-law:    1/32768
    8-bit A-law:     1/32768
    8-bit integer:   128/32768
    16-bit integer:  1/32768
    24-bit integer:  1/(256*32768)
    32-bit integer:  1/(65536*32768)
    float data:      1
 "&lt;number or ratio&gt;" - Specify the scale factor to be applied to
    the data from the file.
</PRE>
</DL>
The default values for the audio file parameters correspond to the following
string.
<PRE>
  "undefined, 0, 8000., native, 1, default"
</PRE>
<P>
<DL>
<DT>
AUDIOPATH:
</DL>
This environment variable specifies a list of directories to be searched when
opening the input audio files.  Directories in the list are separated by
colons (semicolons for Windows).
<H4>Author / version</H4>
P. Kabal / v3r0  2009-03-14
<H4>See Also</H4>
<A HREF="CompAudio.html">CompAudio</A>,
<A HREF="CopyAudio.html">CopyAudio</A>,
<A HREF="ResampAudio.html">ResampAudio</A>
<P>
<HR>
Main Index <A HREF="AFsp.html">AFsp</A>
</BODY>
</HTML>
